Skip to main content

שירות הנחות ארנונה - מפרט טכני

1. סיכום מנהלים​

שירות הנחות ארנונה הוא חלק ממערכת מוני service המאפשרת לדיירים להגיש בקשות להנחות ארנונה, לנהל הנחות קיימות ולקבל מידע על סוגי הנחות זמינות ברשות המקומית. השירות מטפל בתהליכי הגשת בקשות, אימות נתונים, והעברת מידע בין המערכת לספקיות חיצוניות.

השירות פועל כחלק ממערכת microservices וממשק עם:

  • מערכת הרשויות המקומיות
  • ספקיות חיצוניות לניהול הנחות ארנונה
  • מערכת Directus לבדיקות דמו
  • מערכת אימות OAuth2

זרימת עבודה פשוטה:

  1. האזרח נכנס לממשק הנחות ארנונה, בוחר פעולה (הגשת בקשה/ניהול הנחות/צפייה בהנחות)
  2. מוני service קולט את הנתונים וממיר אותם
  3. מוני service פונה לספק בשביל קבלת מידע או הגשת בקשה
  4. מוני service מעבד את המידע ומארגן אותו
  5. מוני service מחזיר לאזרח מידע מפורט על ההנחות

2. תכונות עיקריות​

  • הגשת בקשות הנחת ארנונה: טופס מקוון להגשת בקשה להנחת ארנונה
  • ניהול הנחות קיימות: יצירה, עדכון, מחיקה וצפייה בהנחות ארנונה
  • אימות נתונים: בדיקת תקינות פרטי הדייר והנכס
  • ממשק עם ספקיות חיצוניות: העברת נתונים לספקיות
  • ניהול קבצים: העלאת מסמכים רלוונטיים
  • בדיקת Directus: אימות נתונים מול שרת דמו
  • לוגים ומעקב: מעקב אחר פעולות וטיפול בשגיאות

3. מדריך שימוש מהיר​

3.1 הגשת בקשה להנחת ארנונה​

  1. מלא את פרטי הדייר (שם, תעודת זהות, כתובת, טלפון, אימייל)
  2. הזן פרטי הנכס (כתובת, מספר נכס, גודל, מספר לקוח)
  3. בחר סוגי הנחות מבוקשות
  4. העלה מסמכים רלוונטיים (אישורים, תעודות)
  5. שלח את הבקשה

3.2 ניהול הנחות קיימות​

  1. צפה ברשימת הנחות ארנונה
  2. ערוך הנחה קיימת
  3. מחק הנחה לא רלוונטית
  4. הוסף הנחה חדשה

3.3 קבלת מידע על הנחות​

  1. בחר רשות מקומית
  2. קבל רשימת סוגי הנחות זמינות
  3. צפה בפרטי הנחות ספציפיות

4. תיאור זרימת העבודה​

4.1 ארבעת הזרימות (Gisonim)​

זרימה 1: מהמערך לשירות הנחות ארנונה​

מה קורה בזרימה:

  1. אימות הרשאות דרך RbacGuard ו-@Roles('admin')
  2. אימות נתונים עם class-validator
  3. בדיקת תקינות פרטי הבקשה
  4. שמירת הבקשה במערכת

איזה נתונים מועברים:

  • פרטי דייר (שם, תעודת זהות, כתובת, טלפון, אימייל)
  • פרטי נכס (כתובת, מספר נכס, גודל, מספר לקוח)
  • פרטי הנחות (סוגי הנחות, אחוזי הנחה, הגבלות גודל)
  • מסמכים מצורפים (אישורים, תעודות)
  • מטא-דאטה (מספר הפניה, תאריך שליחה)

איך מטופלות שגיאות:

  • שגיאות אימות מוחזרות עם הודעות בעברית
  • שגיאות שרת מוחזרות עם קוד שגיאה מתאים

מה מוחזר:

  • אישור יצירת הנחה או עדכון הנחה קיימת

זרימה 2: משירות הנחות ארנונה לספקית חיצונית​

מה קורה בזרימה:

  1. חיפוש רשות מקומית לפי קוד יישוב
  2. קבלת פרטי ספקית חיצונית מהרשות
  3. קבלת טוקן אימות מהספקית
  4. העברת נתונים מעובדים לספקית

איזה נתונים מועברים:

  • נתונים מעובדים בפורמט JSON
  • פרטי אימות (טוקן)
  • קוד רשות מקומית

איך מטופלות שגיאות:

  • שגיאות חיבור לספקית
  • שגיאות אימות
  • שגיאות העברת נתונים

מה מוחזר:

  • אישור קבלת הבקשה מהספקית

זרימה 3: מספקית חיצונית לשירות הנחות ארנונה​

מה קורה בזרימה:

  1. עיבוד נתונים על ידי הספקית
  2. עדכון רשומות במערכת הספקית
  3. החזרת תגובה למערכת מוני serviceת

איזה נתונים מועברים:

  • סטטוס עיבוד
  • פרטי הנחות אושרות
  • הודעות שגיאה (אם יש)

איך מטופלות שגיאות:

  • שגיאות עיבוד נתונים
  • שגיאות חיבור
  • שגיאות אימות

מה מוחזר:

  • אישור עיבוד מוצלח או הודעת שגיאה

זרימה 4: משירות הנחות ארנונה למערך​

מה קורה בזרימה:

  1. החזרת DTO מהקונטרולר
  2. סריאליזציה אוטומטית ל-JSON על ידי NestJS
  3. שליחה למשתמש

איזה נתונים מועברים:

  • פרטי הנחות ארנונה (קוד הנחה, אחוז הנחה, הגבלות)
  • אישורי יצירה/עדכון/מחיקה
  • הודעות שגיאה (אם יש)

איך מטופלות שגיאות:

  • שגיאות HTTP: קודי שגיאה סטנדרטיים (400, 401, 403, 500)
  • שגיאות אימות: 401 Unauthorized
  • שגיאות נתונים: 400 Bad Request
  • שגיאות שרת: 500 Internal Server Error

מה מוחזר:

  • JSON Response עם הנתונים המבוקשים

4.2 בדיקת Directus Dummy Server​

מתי נקרא:

  • במצב פיתוח (NODE_ENV === 'development')
  • כאשר הספקית מכוונת לשרת Directus

מה נבדק:

  • תקינות חיבור לשרת Directus
  • זמינות נתונים לבדיקה
  • תקינות טוקן אימות

למה זה נדרש:

  • בדיקות במצב פיתוח
  • סימולציה של ספקיות חיצוניות
  • אימות פונקציונליות ללא ספקיות אמיתיות

איך זה משפיע על הזרימה:

  • מחליף את הספקית החיצונית האמיתית
  • מאפשר בדיקות ללא תלות בספקיות חיצוניות
  • מספק נתוני דמו לבדיקות

5. תלות חיצוניות ושירותים​

5.1 שירותים פנימיים​

  • MongodbServiceService: ניהול מסד נתונים MongoDB
  • SupplierAuthServiceService: אימות עם ספקיות חיצוניות
  • MunicipalitiesService: ניהול רשויות מקומיות
  • LoggingService: מעקב ולוגים

5.2 שירותים חיצוניים​

  • Directus: שרת דמו לבדיקות
  • **ספקיות **: עיבוד בקשות הנחות ארנונה

5.3 תלויות טכניות​

  • NestJS: מסגרת עבודה
  • MongoDB: מסד נתונים
  • Mongoose: ODM למסד נתונים
  • Class-validator: אימות נתונים
  • OAuth2: אימות משתמשים

6. תצורה ומשתני סביבה​

6.1 משתני סביבה נדרשים​

  • NODE_ENV: סביבת עבודה (development/production)
  • db_name: שם מסד הנתונים MongoDB
  • DemoProvider_url: כתובת שרת Directus
  • DemoProvider_token: טוקן אימות ל-Directus
  • mongo_conn: חיבור למסד נתונים MongoDB

6.2 תצורת בסיס נתונים​

  • Collection: muni-arnona-discount - הנחות ארנונה
  • Collection: externalsuppliers - ספקיות חיצוניות
  • Collection: municipalities - רשויות מקומיות

7. מבני נתונים / DTOs / מודלים​

7.1 DTOs עיקריים​

  • MuniArnonaDiscountDto: הנחת ארנונה מוניציפלית
  • FormRequestDto: בקשה להנחת ארנונה
  • PersonalInformationDto: פרטי דייר
  • DiscountsDto: פרטי הנחות
  • DiscountListDto: רשימת הנחות
  • LocalAuthorityDiscountDto: הנחות רשות מקומית

7.2 סכמות MongoDB​

  • MuniArnonaDiscount: הנחות ארנונה
  • DiscountDetail: פרטי הנחה
  • MuniDiscount: הנחת רשות מקומית

8. טיפול בשגיאות ומקרי קצה​

8.1 שגיאות אימות​

  • נתונים חסרים או לא תקינים
  • פורמט תאריכים לא נכון
  • מספרי תעודת זהות לא תקינים
  • כתובות אימייל לא תקינות

8.2 שגיאות חיבור​

  • חיבור לספקית חיצונית נכשל
  • חיבור למסד נתונים נכשל
  • חיבור ל-Directus נכשל

8.3 שגיאות עסקיות​

  • רשות מקומית לא נמצאה
  • ספקית לא זמינה
  • הנחה לא נמצאה

9. אבטחה והרשאות​

9.1 אימות​

  • OAuth2 Guard לכל הבקשות
  • אימות טוקן JWT
  • בדיקת הרשאות משתמש

9.2 הרשאות​

  • רק משתמשים עם תפקיד 'admin' יכולים לגשת לשירות
  • בדיקת הרשאות לפי תפקיד

9.3 הגנות​

  • אימות קלט מחמיר
  • הגנה מפני SQL Injection
  • הגנה מפני XSS

10. בדיקות​

10.1 בדיקות יחידה​

  • בדיקת DTOs עם נתונים תקינים ולא תקינים
  • בדיקת שירותי אימות
  • בדיקת טרנספורמציה של נתונים

10.2 בדיקות אינטגרציה​

  • בדיקת חיבור לספקיות חיצוניות
  • בדיקת חיבור למסד נתונים
  • בדיקת זרימת נתונים מלאה

10.3 בדיקות E2E​

  • בדיקת זרימה מלאה מהמשתמש ועד הספקית
  • בדיקת תרחישי שגיאה
  • בדיקת ביצועים

11. לוגים ומעקב​

11.1 לוגים​

  • לוגים של כל בקשה נכנסת
  • לוגים של שגיאות
  • לוגים של חיבורים לספקיות

11.2 מעקב​

  • מעקב אחר זמני תגובה
  • מעקב אחר שיעורי הצלחה
  • מעקב אחר שגיאות